AppDock 2.51 (14-Nov-2005)

Name:     AppDock II
Purpose:  NeXT style application launcher
Author:   Martin Wrthner
Requires: RISC OS 3.1 or higher, 32-bit compatible (works under RISC OS 5)
Status:   FREEWARE (see [6] below)
WWW:      http://www.mw-software.com/

Sorry, there has been no development on this program for years. It is so far
behind that everything but a complete re-write would be pointless. I have been
planning to do this for years, but I have never managed to actually do it.
Still, I hope that in its present form, AppDock is useful to a few people.

New feature of version 2.42:
  You can give the name of the dock file as parameter, so you can have
  different dock files, e.g. starting AppDock with
    "run ADFS::4.$.!AppDock ADFS::4.$.Docks.Dock1"
  will use the specified file ADFS::4.$.Docks.Dock1 as the dock file. Save
  operations then affect this file. If no parameter is given when starting
  AppDock, the behaviour is as before, i.e. the internal !Dock file is used.
  
New feature of version 2.41:
  Adjust clicking on the dock window toggles the shortcut bar status
  (i.e. hides/displays it).

New feature of version 2.40:
  Pressing Alt+Ctrl+Shift brings the dock to the front, pressing the same
  key combination again puts it to the back. While the dock is at the front,
  it has a red border. This feature can be disabled by choosing the menu item
  Prefs.Front.Never.
    Clicking on the arrow icons of the dock or of the shortcut bar with Menu
  instead of Select or Adjust switches to the very end (down/right arrow) or to
  the very beginning (up/left arrow) of the dock or shortcut bar.

What is AppDock ?
-----------------
AppDock is an application launcher similar to backdrop utilities, in that it
allows application icons to be arranged in a nice way and the applications to
be started without having to deal with directory windows. The design is similar
to the Application Dock that forms part of the NeXT Step system on NeXT
computers. AppDock displays a vertical bar with buttons on which you can drop
applications or directories. It can run down the left or right hand side of
your desktop and adjusts itself to the screen resolution. The dock has "up" and
"down" buttons, so it can have more entries than would fit on the screen.

AppDock also offers a ShortCut bar. It works similar to the application dock,
but it stores ShortCuts for applications. You may define shortcuts for up to 20
applications. AppDock detects which application has the input focus and
displays the shortcut definitions for the corresponding application. By
clicking on one of the ShortCut buttons, the appropriate key combination is
"pressed" by the Application Dock.

You may edit the ShortCut definitions separately for each application. So, you
may assign the ShortCut "Find" and the key shortcut F4 to a button of the
ShortCut bar belonging to Edit and if you click on the button while Edit has
the caret, the Find box is displayed.

The dock and shortcut bars are normally behind all other windows on the
desktop, but you can bring both to the front by pressing Ctrl, Shift and Alt
simultaneously (this feature can be switched off).

How to use it:

1.) The application dock

Simply drag an application or a directory on one of the square buttons on the
vertical bar on the left (or right) side of the desktop.

If you dragged an application:
* its icon is shown on the button
* double-clicking on it starts the application
* dragging a file to it starts the application and loads the file into it
  (provided the application accepts files of this type)
* double-clicking with Shift held down opens the application directory

If you dragged a directory (or a DOSDisc file or any other image file):
* the name is shown on the button. 
* as most names are to long to fit in one row, the application dock tries to
  split the names at a sensible position, e.g. directory names as NewFiles
  are split into 'New' and 'Files'.
* double-clicking on it opens the directory

If you dragged a file to an application on the dock:
* the application is started and the file is loaded into it (e.g. if you drag a
  file to the !Edit icon on the dock, !Edit is started and the file is loaded).

You may define keyboard shortcuts for each entry in the dock, so that you are
able to start them by one keystroke (if no other application intercepts the
shortcut). Simply follow the submenu arrow of the second option of the main
menu. The item is ticked if there is already a shortcut for the corresponding
application/directory. Now select the key and the state of the control keys
(none, Shift, Ctrl or Ctrl-Shift) and confirm the selection by clicking OK. You
may cancel an existing shortcut by clicking on Off. Note that these shortcuts
are not at all related to the shortcuts in the ShortCut bar.

Choosing 'Insert' causes one free button to be inserted before the button
over which Menu was clicked - following dock entries move one button down.

Choosing 'Delete' causes the button over which Menu was clicked to be
deleted - following dock entries move one button up.

Choosing 'Save all' from the menu saves the dock and the shortcuts defined in
the ShortCut bar permanently (the preferences are saved, too).

Note that if you have many applications in the dock, loading may take some
time, as AppDock Filer_Boots the applications in the dock.

The dock bar has multiple "pages". You can jump one page up or down by clicking
on the "up" or "down" arrow button. Clicking Adjust instead of Select moves in
the opposite direction. Clicking Menu jumps to the beginning (up button) or end
(down button) of the used dock entries.


2.) The ShortCut bar

If the horizontal ShortCut bar is not on the screen, you may switch it on
by obtaining the main menu of the apllication dock and choosing
Prefs => ShortCuts => On or by clicking Adjust over the dock bar.

You may switch to edit mode by clicking Menu over the ShortCut bar and choosing
Edit ... In the 'Edit shortcuts' window, you may browse through the defined
applications by clicking the up/down arrow icons or you may define a new
application by entering its name (the name shown in the Task Manager display,
case sensitive !!) in the 'New application:' field and clicking the OK button
next to it. Defined applications may be deleted by clicking the 'Delete'
button.
  Note that the ShortCut bar displays the shortcuts of the currently selected
application. By clicking Menu over one of the rectangular buttons of the
ShortCut bar and following the submenu "ShortCut" you may edit the
corresponding shortcut definition. This can also be achieved by Select-clicking
on a shortcut button.
  You may define the description of the ShortCut to be displayed on the bar by
specifying it next to the text "Action:". Note that the maximum length for the
description is 2 lines of 7 characters. You should leave a space where you want
the lines to be split (e.g. 'Savefile'). You may give the keystroke itself by
positioning the caret in the small icon at the right of the text "ShortCut" and
typing the corresponding key combination. You will hear the system bell and the
key code will appear. Clicking on OK defines the shortcut.

Keystrokes which may be used:
  
Accepted keystrokes are generally all which have a RISCOS code:
 * the function keys alone, with Ctrl, with Shift or with Ctrl-Shift
 * all 'normal characters' from the keyboard
 * Ctrl-A to Ctrl-Z (except Ctrl-U), Ctrl-[, Ctrl-], Ctrl-^, Ctrl-~
 * arrow up/down, Ctrl + any of the arrow keys, Shift + arrow up/down
 * some of the codes Alt+letter (not especially useful)
 
Additional keystrokes under RISC OS 3:
 * Ctrl-U
 * Delete, Copy, Shift-Copy, Ctrl-Copy
 * arrow left/right (alone and + Shift)

Note that other keystrokes e.g. Ctrl-Shift-letter are not accepted, as they
have no own character code. This is a pity as some programs (e.g. Impression
and DeskEdit) make extensive use of Ctrl-Shift-letter combinations. However, to
"send" such keystrokes to an application, much more efforts are necessary. This
is likely to be added in later versions, now that the AppDockSpt module is part
of the application anyway.

The shortcut definition are saved by choosing 'Save all' from one of the menus.

The dock can be toggled between front and back by pressing Alt+Ctrl+Shift. This
feature only works if it is enabled by selecting the corresponding menu item
(Prefs.Front.Alt+Ctrl+Shift). The setting is saved together with the other
options. While the dock is at the front, it has a red border.


3.) Distributing this application

You are encouraged to distribute AppDock and to give it to any RISC OS user you
know! If you give the application away, it is best to delete the !Dock file, as
the person who receives it will probably have his applications stored in
different places on his hard disc, so if you start the dock containing your old
!Dock file, the dock will complain as it won't find the apps mentioned in the
file.

(It is no problem to maintain the shortcuts, as AppDock is not concerned
whether or not you have the applications mentioned in the ShortCuts file).


4.) History

Version 2.51  o finally works with Select3 and Adjust (older versions were
                hidden behind the backdrop due to the new backwindow stack
                in Select3 and above)
Version 2.50  o copes with much larger screen modes (no longer falls over or
                hides entries) - previous versions were limited to 24 icons on
                screen at the same time
              o 32-bit compatible (works under RISC OS 5)
Version 2.46  o various minor restructurings and fixes
Version 2.43: o bug fixed in error handler of save procedure (having the
                application on a read-only medium led to an infinite sequence
                of errors)
              o attempt to make the program a bit more Style-Guide compliant -
                as a side effect it will only work under RISC OS 3 now
Version 2.42: o allows dock file to loaded to be specified as command line
                parameter
              o bug fixed in error handler of save procedure (write-protected
                !Dock and !ShortCuts file no longer led to an infinite sequence
                of errors)
Version 2.41: o Adjust click on the dock toggles the shortcut bar status                         
Version 2.40: o Now detects whether it runs under RO2 or RO3 and uses the RO3
                messages list if possible
              o Dock comes to front if Alt+Ctrl+Shift is pressed and if the
                feature is enabled. Can be put back by pressing the same
                combination again. The key press is detected by the
                AppDockSupport module. Under RO3 this is done via the poll-word
                feature, i.e. no extra null events are needed. Under RO2 the
                key status is checked using null events.
              o bug fixed: if shortcuts were switched off and the settings
                saved, the shortcuts could not be turned on again after
                re-loading the dock (gave error)
              o Clicking on the arrow icons with Menu switches to the very
                beginning or end of the dock/shortcut bar
              o In shortcut edit mode, clicking on a shortcut button with
                Select/Adjust no longer gives an error as it was the case with
                older versions. Instead, the corresponding 'Edit Shortcut'
                window is opened.
Version 2.33: o If running under RO3, Filer_Boot is used instead of running the
                !Boot file of an application
Version 2.32: o Now starts the !Run files of applications directly (starting
                the application itself does not work if it is within an image
                filing system like SparkFS)
Version 2.31: o And I wondered why this new feature of RISC OS 3 never worked
                ... I used the validation string N instead of KN, so you could
                not enter eg Ctrl-U as shortcut. This is now fixed, so under
                RISC OS 3 you have some additional shortcuts
Version 2.30: o Wimp_Poll replaced by Wimp_PollIdle to reduce background
                processing time
              o Sorry for RISC OS 2 users who were confused because the RO2
                sprite pool does not contain the 'up' and 'down' arrow sprites
                which are used in the Edit Shortcuts window. They are now
                contained in the application's private sprite area
Version 2.21: o Small bug fix, posted to Newcastle
Version 2.20: o Final version 2, posted to Newcastle
Version 2.10: o Shift-F12-feature removed, as it interferes with the Pinboard
                (windows vanish if the Desktop is left using F12 while the dock
                is at the front).
Version 2.03: o Now accepts image files (e.g. DOSDisc files) and treats them as
                directories
Version 2.01: o ShortCut bar (automatic detection which app. has the input
                focus, editing facilities etc.)
              o new format (still reads version 1 !Dock files)
              o Credits to Graham Hobson for his suggestion of the ShortCut bar
Version 1.10: o should now really work better with RO3 as the dock window
                doesn't disappear after returning  from the command line
              o the dock comes to the front (like the icon bar) if Shift-F12 is
                pressed
Version 1.06: o if a file is dragged to an application on the dock, the
                application is started with the filename as parameter
              o should now work better with RO3 as the window is re-opened if
                Ctrl-F11 is pressed
Version 1.05: now added Mode 20 icons
Version 1.04: some bugs fixed

Features to add:
              o Using outline fonts instead of system font
              o better user interface for shortcut bar edit operation
              o Dealing with Ctrl-Shift-letter shortcuts (e.g. Ctrl-Shift-I)
              o re-write everything in C
              o allow files to be placed on the dock and allow them
                to be dragged to applications
              o allow dock entries to be dragged to a filer window
              o many more ...


5.) Contacting me

You can contact me at:

Martin Wuerthner
Mannheimer Str. 18
67655 Kaiserslautern
Germany

Phone: +49-(0)631-3608205
Fax:   +49-(0)631-3608203

e-mail: martin@mw-software.com
WWW:    http://www.mw-software.com/


6.) Copyright message

This application, AppDock II, is  Martin Wrthner, 2003 and is FREEWARE.
This means that you may copy it freely provided that
(a) all files of this application are distributed together without modification
    (apart from !ShortCuts and !Dock, see above: "Distributing this
    application...")
(b) this application is not sold for profit without my explicit written
    permission (this includes distribution on CD)
